.TH TLTGEN 1 "DECEMBER 2011" Linux "User Manuals"
.SH NAME
tltgen \- thermistor lookup table generator
.SH SYNOPSIS
.B tltgen --r2
.I r
.B -o
.I output-filename
.B [-A
.I a
.B -B
.I b
.B -C
.I c
.B | --t0
.I t
.B --r0
.I r
.B --beta
.I b
.B | --data-adc
.I list-of-temperature-adc-pairs
.B | --data-resistance
.I list-of-temperature-resistance-pairs
.B ]
.B [other options]...


.SH DESCRIPTION
.B tltgen
generates thermistor lookup tables for thermistors placed in the following
circuit:

    Vref_________
               _|_
              |   |
              |R2 |
              |___|
                |______________V (output)
               _|_     |
              |the|   _|_
              |rmi|   ___C1
              |sto|    |
              |_r_|    |
   GND__________|______|

The output voltage V is assumed to be measured by a 10-bit analog to digital
converter.

The lookup tables generated by tltgen are based on either the beta equation 
(1/T = 1/T0 + 1/B*ln(R/R0)) or the Steinhart-Hart equation 
(1/T = A + B*ln(R) + C*(ln(R)^3)). The latter provides more accurate results
over a larger temperature range, but some thermistor datasheets do not mention
the required A, B and C parameters.

tltgen has the ability to calculate the Steinhart-Hart parameters, when given 
at least 3 measured data points. These datapoints are either 
(temperature:adc-value) pairs or (temperature:resistance) pairs. If more than
3 data points are given, tltgen will use the (non-linear) least squares method
to calculate the Steinhart-Hart parameters that fit most closely to the given
data points.


tltgen outputs a C source file and an accompanying header file. The C file 
contains an array, mapping adc-values to temperatures. The specific structure
of the output array depends on the --output-format option:
.TP
.B ctl
in this output format, the array will contain
.I num-temps 
evenly spread entries over the entire 10-bit ADC range, and the temperature at
each of these points is formatted as a short signed integer
.TP
.B tlt-full-int16
in this output format, the array will contain an entry for each possible 10-bit
ADC value and the temperature at each of these 1024 values is formatted as a
16-bit signed integer
.TP
.B tlt-full-float
in this output format, the array will contain an entry for each possible 10-bit
ADC value and the temperature at each of these 1024 values is formatted as a
float
.P
To run tltgen, either the three beta equation parameters (t0,r0,beta), or the
three Steinhart-Hart parameters (A,B,C), or at least three data points must be
given as options. Next to these parameters, the resistance of resistor r2 in 
the circuit above and the base name of the .c and .h output files must also
be given.


.SH OPTIONS
.TP
.BI --r2 " resistance"
The
.I resistance
(float) in ohms of resistor r2 in the thermistor circuit above.
.TP
.BI "-o, --output" " filename"
The base name of the .c and .h output files.
.TP
.BI --data-adc " temp:adc..."
List of at least three (temperature:adc) data points (float:float), in order to
calculate the Steinhart-Hart parameters. The data points can be separated by
commas or whitespace, but if whitespace is used, the list must be enclosed in
double quotes.
.TP
.BI --data-resistance " temp:resistance..."
List of at least three (temperature:resistance) data points (float:float), in
order to calculate the Steinhart-Hart parameters. The data points can be
separated by commas or whitespace, but if whitespace is used, the list must be
enclosed in double quotes.
.TP
.BI --input-scale " C|F|K"
The temperature scale in which the input temperature parameters are given.
.B C
means Celcius (the default), 
.B F
means Fahrenheit and
.B K
means Kelvin. The input temperature parameters on which this option has an
influence are
.I t0
and the first part of the
.I data-adc
or
.I data-resistance
data points.
.TP
.BI --output-scale " C|F|K"
The temperature scale in which the output temperatures are given.
.B C
means Celcius (the default),
.B F
means Fahrenheit and
.B K
means Kelvin.
.TP
.BI --output-format " ctl|tlt-full-int16|tlt-full-float"
The structure of the output array in the .c file:
.RS
.TP
.BI ctl
in this output format, the array will contain
.I num-temps 
evenly spread entries over the entire 10-bit ADC range, and the temperature at
each of these points is formatted as a short signed integer
.TP
.BI tlt-full-int16
in this output format, the array will contain an entry for each possible 10-bit
ADC value and the temperature at each of these 1024 values is formatted as a
16-bit signed integer
.TP
.BI tlt-full-float
in this output format, the array will contain an entry for each possible 10-bit
ADC value and the temperature at each of these 1024 values is formatted as a
float
.RE
.TP
.BI --num-temps " n"
The number of temperatures to output when using the
.I ctl
output format.
.TP
.BI -A " a"
The A parameter (float) for the Steinhart-Hart equation.
.TP
.BI -B " b"
The B parameter (float) for the Steinhart-Hart equation.
.TP
.BI -C " c"
The C parameter (float) for the Steinhart-Hart equation.
.TP
.BI --t0 " temp"
The t0 parameter (float) for the beta equation. This is the temperature of
the thermistor when it has resistance
.I r0
.
.TP
.BI --r0 " resistance"
The r0 parameter (float) for the beta equation. This is the resistance in ohms 
of the thermistor when it has temperature
.I t0
.
.TP
.BI --beta " beta"
The beta parameter (float) for the beta equation.
.TP
.B "-p, --parameters-only"
Only print the beta or Steinhart-Hart parameters that would be used to 
calculate the lookup tables, but do not actually write anything to a file.
.TP
.B "-f, --force"
Overwrite the output .c and .h files if they already exist.

.SH EXAMPLES
.IP \[bu]
Generate a ctl-style lookup table with 20 entries, in a file named 
thermistor_table.c and accompanying header file thermistor.h, for a thermistor
with a resistance of 100 Kohm at 25 degrees celcius and a beta-value of 4036, 
where resistor r2 in the thermistor circuit has a value of 4700 ohm:

tltgen --r2 4700 --t0 25 --r0 100000 --beta 4036 --output-format ctl
--num-temps 20 -o thermistor_table
.IP \[bu]
Generate a tlt-full-int16-style lookup table, in a file named 
thermistor_table.c and accompanying header file thermistor.h, for a thermistor
with Steinhart-Hart parameters A:0.000491834, B:0.000241745 and C:5.49476e-08,
where resistor r2 in the thermistor circuit has a value of 4700 ohm:

tltgen --r2 4700 -A 0.000491834 -B 0.000241745 -C 5.49476e-08
--output-format tlt-full-int16 -o thermistor_table
.IP \[bu]
Generate a tlt-full-float-style lookup table, in a file named 
thermistor_table.c and accompanying header file thermistor.h, for a thermistor
having resistance 100 Kohm at 25 degrees Celcius, 33 Kohm at 50 degrees and 
5.2 Kohm at 100 degrees, where resistor r2 in the thermistor circuit has a
value of 4700 ohm:

tltgen --r2 4700 --data-resistance "25:100000 50:33000 100:5200"
--output-format tlt-full-float -o thermistor_table
.IP \[bu]
Generate a ctl-style lookup table with 60 entries, in a file named 
thermistor_table.c and accompanying header file thermistor.h, for a thermistor
having adc value 977 at 25 degrees Celcius, 852 at 60 degrees and 305 at 150 
degrees, where resistor r2 in the thermistor circuit has a value of 4700 ohm:

tltgen --r2 4700 --data-adc "25:967 60:852 150:305" --output-format ctl
--num-temps 60 -o thermistor_table
.SH HISTORY
This is the first version of tltgen.
.SH AUTHORS
Pieter Agten <pieter.agten@gmail.com>
.SH CREDITS
tltgen was inspired by the createTemperatureLookup.py python script from the
RepRap project, which unfortunately does not mention its author.
.SH COPYRIGHT
Copyright (C) 2011 Pieter Agten
.PP
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and
this notice are preserved.
